//
//  DMLifecycleStateManager.h
//  DualMediationSDK
//
//  生命周期状态管理器
//  负责管理应用生命周期状态的转换和查询
//

#import <Foundation/Foundation.h>
#import "../Types/DMLifecycleTypes.h"

NS_ASSUME_NONNULL_BEGIN

/**
 * 生命周期状态变化通知
 */
// 生命周期状态变更通知
FOUNDATION_EXPORT NSNotificationName const DMLifecycleStateDidChangeNotification;

// userInfo 字段
FOUNDATION_EXPORT NSString * const DMLifecycleStateChangeUserInfoKeyPreviousState;
FOUNDATION_EXPORT NSString * const DMLifecycleStateChangeUserInfoKeyCurrentState;
FOUNDATION_EXPORT NSString * const DMLifecycleStateChangeUserInfoKeyTimestamp;

/**
 * 状态历史记录项
 */
@interface DMLifecycleStateHistoryItem : NSObject
@property (nonatomic, assign) DMLifecycleState state;
@property (nonatomic, assign) DMLifecycleEvent triggerEvent;
@property (nonatomic, strong) NSDate *timestamp;
@property (nonatomic, assign) NSTimeInterval duration; // 在该状态停留的时间
@end


/**
 * 生命周期状态管理器
 * 负责管理应用生命周期状态的转换、查询和历史记录
 */
@interface DMLifecycleStateManager : NSObject

#pragma mark - 单例访问

/**
 * 获取状态管理器单例
 * @return 状态管理器实例
 */
+ (instancetype)sharedManager;

#pragma mark - 状态管理

/**
 * 当前生命周期状态
 */
@property (nonatomic, assign, readonly) DMLifecycleState currentState;

/**
 * 获取当前生命周期状态（便捷方法）
 * @return 当前生命周期状态
 */
- (DMLifecycleState)getCurrentState;

/**
 * 上一个生命周期状态
 */
@property (nonatomic, assign, readonly) DMLifecycleState previousState;

/**
 * 最后一次状态变化的时间戳
 */
@property (nonatomic, strong, readonly) NSDate *lastStateChangeTime;

/**
 * 当前状态持续时间（秒）
 */
@property (nonatomic, assign, readonly) NSTimeInterval currentStateDuration;

/**
 * 是否已初始化
 */
@property (nonatomic, assign, readonly) BOOL isInitialized;

#pragma mark - 状态转换

/**
 * 转换到新的生命周期状态
 * @param newState 新的生命周期状态
 * @param event 触发状态转换的事件
 * @return 是否成功转换状态
 */
- (BOOL)transitionToState:(DMLifecycleState)newState withEvent:(DMLifecycleEvent)event;

/**
 * 转换到新的生命周期状态（便捷方法，自动推断事件）
 * @param newState 新的生命周期状态
 * @return 是否成功转换状态
 */
- (BOOL)transitionToState:(DMLifecycleState)newState;

/**
 * 强制设置生命周期状态（跳过验证）
 * @param state 要设置的状态
 * @param event 触发状态设置的事件
 * @warning 此方法会跳过状态转换验证，请谨慎使用
 */
- (void)forceSetState:(DMLifecycleState)state withEvent:(DMLifecycleEvent)event;

/**
 * 重置状态管理器到初始状态
 */
- (void)reset;

#pragma mark - 状态查询

/**
 * 检查应用是否处于活跃状态
 * @return YES 如果应用处于活跃状态
 */
- (BOOL)isActive;

/**
 * 检查应用是否处于前台
 * @return YES 如果应用处于前台
 */
- (BOOL)isForeground;

/**
 * 检查应用是否处于后台
 * @return YES 如果应用处于后台
 */
- (BOOL)isBackground;

/**
 * 检查应用是否已暂停
 * @return YES 如果应用已暂停
 */
- (BOOL)isSuspended;

/**
 * 检查应用是否已终止
 * @return YES 如果应用已终止
 */
- (BOOL)isTerminated;

/**
 * 检查状态转换是否有效
 * @param fromState 起始状态
 * @param toState 目标状态
 * @param event 触发事件
 * @return YES 如果状态转换有效
 */
- (BOOL)isValidTransitionFromState:(DMLifecycleState)fromState 
                           toState:(DMLifecycleState)toState 
                         withEvent:(DMLifecycleEvent)event;

#pragma mark - 状态历史

/**
 * 获取状态历史记录
 * @param limit 返回记录的最大数量，0表示返回所有记录
 * @return 状态历史记录数组，按时间倒序排列
 */
- (NSArray<DMLifecycleStateHistoryItem *> *)getStateHistory:(NSUInteger)limit;

/**
 * 获取指定状态的总停留时间
 * @param state 要查询的状态
 * @return 总停留时间（秒）
 */
- (NSTimeInterval)getTotalTimeInState:(DMLifecycleState)state;

/**
 * 获取状态转换次数
 * @param fromState 起始状态，DMLifecycleStateUnknown表示任意状态
 * @param toState 目标状态，DMLifecycleStateUnknown表示任意状态
 * @return 转换次数
 */
- (NSUInteger)getTransitionCount:(DMLifecycleState)fromState toState:(DMLifecycleState)toState;

/**
 * 清除状态历史记录
 */
- (void)clearStateHistory;

#pragma mark - 状态监听

/**
 * 状态变化回调块
 * @param previousState 上一个状态
 * @param currentState 当前状态
 * @param event 触发事件
 * @param timestamp 变化时间
 */
typedef void(^DMLifecycleStateChangeBlock)(DMLifecycleState previousState, 
                                          DMLifecycleState currentState, 
                                          DMLifecycleEvent event, 
                                          NSDate *timestamp);

/**
 * 添加状态变化监听器
 * @param identifier 监听器标识符
 * @param block 状态变化回调块
 */
- (void)addStateChangeListener:(NSString *)identifier block:(DMLifecycleStateChangeBlock)block;

/**
 * 移除状态变化监听器
 * @param identifier 监听器标识符
 */
- (void)removeStateChangeListener:(NSString *)identifier;

/**
 * 移除所有状态变化监听器
 */
- (void)removeAllStateChangeListeners;

#pragma mark - 调试和诊断

/**
 * 获取状态管理器的调试信息
 * @return 包含调试信息的字典
 */
- (NSDictionary *)getDebugInfo;

/**
 * 验证状态管理器的内部一致性
 * @return YES 如果状态一致
 */
- (BOOL)validateInternalConsistency;

/**
 * 导出状态历史为JSON格式
 * @return JSON字符串，如果导出失败返回nil
 */
- (nullable NSString *)exportStateHistoryAsJSON;

@end

NS_ASSUME_NONNULL_END
